/** \file
*/
/* ************************************************************************* **
** $Id: dmbimage.h,v 1.1.1.1 2009-02-13 22:36:43 beliloi Exp $
**                 Proprietary and Confidential Information                  **
**                                                                           **
**                Copyright (c) 2003 Oasis Semiconductor Inc.                **
**                                                                           **
**  This software contains proprietary and confidential material which is    **
**  property of Oasis Semiconductor Inc.                                     **
**                                                                           **
** ************************************************************************* */
#ifndef _dmbimage_h_
#define _dmbimage_h_
/******************************************************************************
*  FILE FORMAT:
*      1. ENUMERATIONS
*      2. DEFINES
*      3. STRUCTURES
*      4. ALLOCS
*      5. FUNCTIONS
******************************************************************************/
# include "type.h"
//# include "os/mem.h"   // for MemPageNum_t

# if SDK_VERSION >= 5
#  include "dc_type.h"
#  include "dc_return_codes.h"
#  include "dc_dmb_api.h"
#  define DMBIMAGE_CHANNELS DC_DMBIMAGE_CHANNELS
#  define DMBIMAGE DC_DMBIMAGE
#  define pDMBIMAGE DC_DMBIMAGE*
#  define DMBIMAGE_BITDEPTH DC_DMBIMAGE_BITDEPTH
#  define DMBIMAGE_FORMAT DC_DMBIMAGE_FORMAT
#  define DMBFILE_HEADER DC_DMBFILE_HEADER
#  include "dc_dmbimage_api.h"
# else
/******************************************************************************
*  1. ENUMERATIONS
******************************************************************************/
//
/*!\struct DMBIMAGE_STRUCT
   \brief DMB Image descriptor.

    Images (scans, copies, faxes) which are being processed by the HAL are
    stored in dynamic memory blocks (DMBs).  The attributes of a DMB image are
    specified using the DMB image descriptor stored in this structure.

    DMB image channel defintions:
     - C = Cyan
     - M = Magenta
     - Y = Yellow
     - K = Black
     - Kt = Text Black
     - Kp = Photo Black
     - P = Protective (a.k.a. seal or transparent).
     - R = Red
     - G = Green
     - B = Blue
     - YUV = Y is brightness or lightness; U is blue minus Y; V is red minus Y.
     - LAB = L is luminance; A is chromatic value of green to red; B is from blue to yellow.

    Simple multi-channel DMB images:

    The DMB image mechanism supports two methods of dealing with multi-channel
    (ie. RGB, CMYK, etc) images.  The simplest method is to arrange the image
    data in a scanline interleaved form.  In this case, the DMB image channels
    member will indicate the number (and sometimes type) of channels making
    up the image.  The DMB image stride member will define the address increment
    in bytes required to move from one channel scanline to the next channel
    scanline.  Thus, for multi-channel images, the stride from one scanline
    to the next scanline of same channel type will be

         ( N ) * (DMB image member sride)

    where N is the number of channels in the image.

    Superplanar multi-channel DMB images:

    The other method of dealing with multi-channel images is to represent
    each of the image channels using a different DMB image.  This is called a
    superplanar DMB image.  A superplanar DMB image consists of a parent
    DMB image and a specified number of children DMB images.  The parent DMB
    image includes a list of pointers to DMB image structures which define
    the children DMB images.  Likewise, each children DMB image includes
    a pointer to the parent DMB image.

    During the course of its lifetime, a DMB image structure will be manipulated
    by up to three agents: an initializer, the DMB image producer, and the DMB
    image consumer.

    The DMB image initializer must prepare the DMB image description before
    handing it to the producing agent for image creation.  The initializer
    performs the following initializations:

     - superPlanar = 1 for parent DMB of complex multi-channel image,
                     0 for simple DMB image or child DMB image
     - headDMBIndex = MEM_NULL
     - currentHeadDMBIndex = MEM_NULL
     - validScanlines = 0
     - validBytes = 0
     - maxDMBs = indicate max # of DMBs to be used, 0 for unlimited
     - allocDMBs = 0
     - freeDMBs = 0
     - readDMBs = 0
     - creationOngoing = 0
     - consumptionOngoing = 0
     - *parent = superplanar ? &dmbParent : NULL;
     - *child[] = superplanar ? {&dmbChild0, &dmbChild1,...} : {NULL,NULL,...}
     - currency_detect_valid = 0
     - currency_detected = 0

    Before depositing any data into the DMB image, the producer will fill in the
    static DMB image attributes specified by the variables channels, bitdepth,
    format, width, height, heightMode, and stride.  After these parameters are
    specified, the producer will set creationOngoing to 1 and begin depositing
    image data.  As this image creation process occurs, the headDMBIndex,
    validScanlines, validBytes, and allocDMBs will be updated.  Once the
    producer has completed creating the image it will clear the creationOngoing
    variable.

    A DMB image consumer (drain) is an agent which consumes and frees the DMBs making
    up the DMB image.  Before a consumer begins freeing the DMBs making up the
    DMB image, it will set the consumptionOngoing variable to 1.  As the
    consumption and freeing process continues, the currentHeadDMBIndex and
    freeDMBs variables will be updated.  When the consumer has freed the final
    DMB of the image, it will set currentHeadDMBIndex to MEM_NULL_EOP and then
    clear the consumptionOngoing variable.
*/

/*!\struct DMBFILE_HEADER_
  \brief DMB file header.

  Descriptor that is added to the beginning of dmbimage files that may
  be manipulated by PC software.  This structure is not relevant to
  firmware, but is used to make software more robust to changes in
  dmbimage layout, by encoding size and version information at the
  beginning of the file.

*/

#define DMBIMAGE_CHANNELS_CountBits 4
#define DMBIMAGE_CHANNELS_CountMask (0x0f)
#define DMBIMAGE_CHANNELS_nChannels(x) (x & DMBIMAGE_CHANNELS_CountMask)
#define ChannelCountAndType(count, type) \
  (count | (type << DMBIMAGE_CHANNELS_CountBits))

/*!
 ** \enum DMBIMAGE_CHANNELS
   Defines which channel the DMB image will use.  */
typedef enum {

  DMBIMAGE_CHANNELS_UNKNOWN   = ChannelCountAndType(0,0), //!< Unknown channel content

  DMBIMAGE_CHANNELS_1         = ChannelCountAndType(1,0), //!< generic 1 channel
  DMBIMAGE_CHANNELS_K         = ChannelCountAndType(1,1), //!< Use K channel
  DMBIMAGE_CHANNELS_Kt        = ChannelCountAndType(1,2), //!< Use Kt channel
  DMBIMAGE_CHANNELS_C         = ChannelCountAndType(1,3), //!< Use C channel
  DMBIMAGE_CHANNELS_M         = ChannelCountAndType(1,4), //!< Use M channel
  DMBIMAGE_CHANNELS_Y         = ChannelCountAndType(1,5), //!< Use Y channel

  DMBIMAGE_CHANNELS_2         = ChannelCountAndType(2,0), //!< generic 2 channel
  DMBIMAGE_CHANNELS_CK        = ChannelCountAndType(2,1), //!< for color/mono ink density maps
  DMBIMAGE_CHANNELS_KtKp      = ChannelCountAndType(2,2), //!< Use KtKp channel
  DMBIMAGE_CHANNELS_KpP       = ChannelCountAndType(2,3), //!< Use Kp, P channels

  DMBIMAGE_CHANNELS_3         = ChannelCountAndType(3,0), //!< generic 3 channel
  DMBIMAGE_CHANNELS_RGB       = ChannelCountAndType(3,1), //!< Use RGB channel
  DMBIMAGE_CHANNELS_YUV       = ChannelCountAndType(3,2), //!< Use YUV channel
  DMBIMAGE_CHANNELS_YCrCb     = ChannelCountAndType(3,2), //!< Use YCrCb channel
  DMBIMAGE_CHANNELS_LAB       = ChannelCountAndType(3,3), //!< Use LAB channel
  DMBIMAGE_CHANNELS_CMY       = ChannelCountAndType(3,4), //!< Use CMY channel

  DMBIMAGE_CHANNELS_4         = ChannelCountAndType(4,0), //!< generic 4 channel
  DMBIMAGE_CHANNELS_CMYK      = ChannelCountAndType(4,1), //!< Use CMYK channel
  DMBIMAGE_CHANNELS_CMYKt     = ChannelCountAndType(4,2), //!< Use CMYKt channel
  DMBIMAGE_CHANNELS_CMYKp     = ChannelCountAndType(4,3), //!< Use CMYKp channel

  DMBIMAGE_CHANNELS_5         = ChannelCountAndType(5,0), //!< generic 5 channel
  DMBIMAGE_CHANNELS_CMYKpP    = ChannelCountAndType(5,1), //!< Use CMYKpP channel
  DMBIMAGE_CHANNELS_CMYKtKp   = ChannelCountAndType(5,2), //!< Use CMYKtKp channel

  DMBIMAGE_CHANNELS_6         = ChannelCountAndType(6,0), //!< generic 5 channel
  DMBIMAGE_CHANNELS_CMYKcm    = ChannelCountAndType(6,1), //!< Use CMYKcm channel
  DMBIMAGE_CHANNELS_CMYcm     = ChannelCountAndType(6,2), //!< Use CMY.cm channel
  DMBIMAGE_CHANNELS_CMYKtKpP  = ChannelCountAndType(6,3)  //!< Use CMYKtKpP channel

} DMBIMAGE_CHANNELS;


/*! \enum DMBIMAGE_BITDEPTH
   \ifnot TestLabel
   Defines the bit depth of the DMB Image.
   */
 typedef enum {
  DMBIMAGE_BITDEPTH_1, //!< Bit depth is 1
  DMBIMAGE_BITDEPTH_8, //!< Bit depth is 8
  DMBIMAGE_BITDEPTH_2, //!< Bit depth is 2
  DMBIMAGE_BITDEPTH_3, //!< Bit depth is 3
  DMBIMAGE_BITDEPTH_4, //!< Bit depth is 4
  DMBIMAGE_BITDEPTH_5, //!< Bit depth is 5
  DMBIMAGE_BITDEPTH_6, //!< Bit depth is 6
  DMBIMAGE_BITDEPTH_7, //!< Bit depth is 7
  DMBIMAGE_BITDEPTH_UNKNOWN, //!< Unknown bit depth
  DMBIMAGE_BITDEPTH_16 //!< Bit depth is 16 (defined for audio formats: mp3, wav, pcm)
} DMBIMAGE_BITDEPTH;

///   \endif


/*! \enum DMBIMAGE_FORMAT
   Defines the format of the DMB Image.
   */
typedef enum {
  DMBIMAGE_FORMAT_RAW, //!< Raw format
  DMBIMAGE_FORMAT_LLJ, //!< LLJ format
  DMBIMAGE_FORMAT_JBIG, //!< JBIG format
  DMBIMAGE_FORMAT_SIMPLE, //!< Simple format
  DMBIMAGE_FORMAT_JPEG, //!< JPEG format
  DMBIMAGE_FORMAT_TIFF, //!< TIFF format
  DMBIMAGE_FORMAT_BNE, //!< Bert and Ernie format
  DMBIMAGE_FORMAT_EXTENT, //!< Extent Data format
  DMBIMAGE_FORMAT_UNKNOWN, //!< Unknown format

/** Audio Formats ****************************************\
**   These formats will use only 5 of the parameters
**   defined within the DMBIMAGE struct:
**     channels, bits per sample, sample rate,
**     valid bytes, and format.
**   They will map to the DMBIMAGE params as follows:
**     channels           => channels
**     bits per sample    => bitdepth
**     sample rate        => stride
**     valid bytes        => validBytes
**     format             => format
**********************************************************/
  DMBIMAGE_FORMAT_MP3, //!< MP3 audio format
  DMBIMAGE_FORMAT_WAV, //!< WAVE audio format
  DMBIMAGE_FORMAT_PCM //!< PCM audio format

} DMBIMAGE_FORMAT;

/*! \enum DMBIMAGE_HEIGHTMODE
   Defines the height mode of the DMB Image.
   */
typedef enum {
  DMBIMAGE_HEIGHTMODE_KNOWN, //!< ..
  DMBIMAGE_HEIGHTMODE_ATLEAST, //!< ..
  DMBIMAGE_HEIGHTMODE_ATMOST, //!< ..
  DMBIMAGE_HEIGHTMODE_UNKNOWN
} DMBIMAGE_HEIGHTMODE;

/*! \enum DMBIMAGE_SAMPLERATE
   Defines the sample rates available for
   audio formats: MP3, WAV, PCM.
   (the audio formats use the stride parameter
   to indicate the sample rate)
   */
typedef enum {
  DMBIMAGE_SAMPLERATE_11025=11025,
  DMBIMAGE_SAMPLERATE_22050=22050,
  DMBIMAGE_SAMPLERATE_44100=44100,
  DMBIMAGE_SAMPLERATE_UNKNOWN=0
} DMBIMAGE_SAMPLERATE;

/******************************************************************************
*  2. DEFINES
******************************************************************************/
/*
** Macro to check if DMBIMAGE has been initialized.  This is only valid before
** the DMBIMAGE has begun being consumed!
*/
#define DMBIMAGE_MAX_NUMBER_CHILD   4
#define DMBIMAGE_INITIALIZED(dmbP)    (!MemPageNullP(dmbP->headDMBIndex))

#define DMBIMAGE_VERSION 5      //Used in file header

/******************************************************************************
*  3. STRUCTURES
******************************************************************************/
typedef struct DMBIMAGE_STRUCT {

  /// Defines whether a DMB image is the parent DMB image of a complex multi-
  /// channel image.  If superPlanar = 1, children DMB images will be
  /// specified via the atribute child[].  This field is 0 for simple DMB
  /// images and children DMB images.
  /// This field is set to 0 or 1 by the initializer.
  boolean superPlanar;

  /// Defines the type of channel; Use an enumerated type from DMBIMAGE_CHANNEL.
  /// With supperPlanar set, channels of parent and children DMBImage
  /// are different. Channel of parent DMBImage represents a composite channel
  /// of output such as CMYK or CMYKcm. A child DMB image has only one channel
  /// type such as K, C, M, or Y.
  /// Updated by Source.
  ALIAS(UINT8,DMBIMAGE_CHANNELS) channels;  // one of DMBIMAGE_CHANNEL_*
  /// Defines the bit depth; Use an enumerated type from DMBIMAGE_BPP.
  /// A parent and child DMBImages have same bitdepth.
  /// Updated by Source.
  ALIAS(UINT8,DMBIMAGE_BITDEPTH) bitdepth;  // one of DMBIMAGE_BPP_*
  /// Defines the format used; Use an enumerated type from DMBIMAGE_FORMAT.
  /// A parent and child DMBImages have same format.
  /// Updated by Source.
  ALIAS(UINT8,DMBIMAGE_FORMAT) format;    // one of DMBIMAGE_FORMAT_*

  /// Width of the image.
  /// A parent and child DMBImages have same format.
  /// Updated by Source.
#ifdef DMBIMAGE_LARGE_SIZE
  UINT32 width;
#else
  UINT16 width;
#endif /* DMBIMAGE_LARGE_SIZE */

  /// Height of the image.
  /// A parent and child DMBImages have same format.
  /// Updated by Source.
#ifdef DMBIMAGE_LARGE_SIZE
  UINT32 height;
#else
  UINT16 height;
#endif /* DMBIMAGE_LARGE_SIZE */

  /// In some cases, during creation of the image, the true image height will be unknown
  /// For example, a sheet-fed scanner may have accomodation for Short-Sheet and
  /// Extended-Sheet sizes.   In these cases, the height will be set to the
  /// target height and the heightMode value will be set in order to give as
  /// much information about the eventual height as possible. Use an enumerated type
  /// from DMBIMAGE_HEIGHTMODE.
  /// Updated by Source.
  ALIAS(UINT8,DMBIMAGE_HEIGHTMODE) heightMode;  // one of DMBIMAGE_HEIGHTMODE_*
#if (!NEW_MEM_C) && (SDK_VERSION<3)
  UINT8 pad1;
#endif

  /// The headDMBIndex field defines the index to the first DMB in the linked
  /// list of DMBs which store the image data.  The initializer of the DMB image
  /// will initialize to MEM_NULL.  The headDMBIndex field will be subsequently
  /// written by the source of data for the DMBImage with the value of the
  /// first link DMB.  It will thereafter remain static during the lifetime of
  /// the DMBImage.
  ///
  /// When superPlanar is 1, the headDMBImage of parent DMBImage will remain
  /// MEM_NULL over the lifetime of the DMB image.  (No DMBs are associated
  /// with the parent DMB image.)
  ///
  /// Updated by Source.
  MemPageNum_t headDMBIndex; //<! Index to first DMB in linked list of image data.
#if (!NEW_MEM_C) && (SDK_VERSION<3)
  UINT8 pad2;
#endif

  /// The currentHeadDMBIndex is used by the consumer to track the current head
  /// DMB in the linked list.  As DMBs are comsumed and freed, currentHeadDMBIndex
  /// is updated to the next DMB by the consumer. (see freeDMBs)   Initialized to
  /// MEM_NULL.
  ///
  /// The currentHeadDMBIndex of parent DMBImage when superPlanar is set
  /// is not used and will this remain at MEM_NULL over the lifetime of the
  /// DMB image.
  ///
  /// Updated by Drain.
  MemPageNum_t currentHeadDMBIndex; //<! Current first DMB in the linked list.
#if (!NEW_MEM_C) && (SDK_VERSION<3)
  UINT8 pad3;
#endif

  /// Stride of the image, in bytes. Written by the image source.  It is a means of
  /// reserving scanline buffer in terms of the number of bytes. The buffer can
  /// be bigger than the actual width of the image if needed. Due to hardware
  /// requirements, this buffer must have a 32 byte boundary; for a bitonal scanline,
  /// stride e width/8 and remainder of (stride/32) = 0, and for RGB, stride e
  /// width*3 and remainder (stride/32) = 0. For compressed data, this field
  /// reserves the buffer for what the scanline would need if decoded.
  /// Please note that the stride
  /// is written by the provider of the DMBImage data and as such will
  /// not be valid until headDMBIndex has been written to a value other
  /// than MEM_NULL.
  /// For audio formats (mp3, wav, pcm) stride will represent the sample rate.
  /// Use an enumerated type from DMBIMAGE_SAMPLERATE.
  /// Updated by Source.
  UINT32 stride;

  /// The validScanlines variable reports the number of scanlines for which data
  /// has been written to DMBs.  Initialized to 0.  The validScanlines member
  /// allows the consumer to determine the amount of valid image data.  This
  /// field is particularly useful for compressed image format, in which the
  /// number of scanlines is not directly related to amount of data in DMBs.
  /// The validScanlines of parent DMBImage when superPlanar is set is not
  /// used and will thus remain at its initialized value of 0.
  /// Updated by Source.
#ifdef DMBIMAGE_LARGE_SIZE
  UINT32 validScanlines;
#else
  UINT16 validScanlines;
#endif /* DMBIMAGE_LARGE_SIZE */

  /// The validBytes variable reports the number of bytes which have been written
  /// to DMBs.  Initialized to 0.
  /// The validScanlines of parent DMBImage when superPlanar is set is not
  /// used and will thus remain at its initialized value of 0.
  /// Updated by Source.
  UINT32 validBytes;

  /// This field is used to limit the memory footprint of the image as it streams
  /// thru the DMB image mechanism.  The value written to maxDMBs represents the
  /// maximum net number of DMBs which should be used by the DMB image.  A maxDMBs
  /// value of 0 indicates unlimited.  maxDMBs is used along with allocDMBs and
  /// freeDMBs to implement the memory footprint limiting.
  ///
  /// When superPlaner is set, the parent and children maxDMBs members will be
  /// used for memory footprint limiting.  The children maxDMBs values will be
  /// used in the normal way.  In addition, the parent maxDMBs can be used to
  /// provide an overall maximum number of DMBs for combination of all children
  /// DMB images.
  ///
  /// This field is set by the initializer.
  UINT16 maxDMBs;

  /// An image source will increment allocDMBs each time it places image data into
  /// a newly allocated DMB. Its use is tied with maxDMBs and freeDMBs.
  /// For a parent DMB image, the allocDMBs variable will be incremented whenever
  /// an alloc is performed for one of the child DMB images.
  /// Updated by Source. Initialized to 0.
  UINT16 allocDMBs;

  /// The image consumer (drain) will increment free DMBs each time it releases a
  /// DMB back to the memory manager. Its use is tied with maxDMBs and allocDMBs.
  /// For a parent DMB image, the freeDMBs variable will be incremented whenever
  /// an free is performed for one of the child DMB images.
  /// Updated by Drain. Initialized to 0.
  UINT16 freeDMBs;

  /// The readDMBs member is used to support a debugging feature which allows a
  /// DMB image which is being streamed from provider to consumer to be uploaded
  /// via DGBMON to a host PC.  When this debugging feature is enabled, readDMBs
  /// is incremented as each DMB is uploaded to the PC.  The primary consumer,
  /// which must be aware that debug mode is enabled, will not free DMBs until
  /// associated DMBs have been uploaded to the PC (as indicated via readDMBs).
  /// Updated by DBGMON. Initialized to 0.
  UINT16 readDMBs;

  /// creationOngoing and consumptionOngoing indicate whether the image is being
  /// actively created
  /// (for example, when a scan is occuring to the image) or consumed (for
  /// example, when it is being printed for the final time).  The flag
  /// creationOngoing will be set no later than when headDMBIndex is first set
  /// to non-MEM_NULL and will be cleared no earlier than when the DMB linked
  /// list is terminated with the MEM_NULL_EOP value. Initialized to 0.
  /// The creationOngoing of parent DMBImage when superPlanar is set
  /// is not used and will thus remain 0 throughout the lifetime of the DMB
  /// image.
  /// Updated by Source.
  UINT8 creationOngoing;

  /// creationOngoing and consumptionOngoing indicate whether the image is being
  /// actively created (for example, when a scan is occuring to the image) or consumed
  /// (for example, when it is being printed for the final time).  The flag
  /// consumptionOngoing is set no later than when currentHeadDMBIndex is first updated
  /// during a free operation, and is cleared no earlier than when the final
  /// DMB associated with the image is freed. Initialized to 0.
  /// The consumptionOngoing of parent DMBImage when superPlanar is set
  /// is not used and will thus remain 0 throughout the lifetime of the DMB
  /// image.
  /// Updated by Drain.
  UINT8 consumptionOngoing;

  /// The parent memory points to the entry of parent DMBImage if the current
  /// DMB image is a child DMB image.  Otherwise, this field is NULL.
  /// Initialized to NULL or parent pointer by the initializer.
  struct DMBIMAGE_STRUCT *parent;

  /// For parent DMB images when superPlanar = 1, these fields define pointers
  /// to children DMB Images.  In other cases, these fields are NULL.
  /// Initialized to NULL or children pointers by the initializer.
  struct DMBIMAGE_STRUCT *child[DMBIMAGE_MAX_NUMBER_CHILD];

#ifdef CURRENCY_DETECT
  // should be CLEARED at DMBImage init, along with headIndex, etc.
  // goes TRUE to indicate that 'currency_detected' is valid.
  boolean currency_detect_status_valid;

  // should be CLEARED at DMBImage init, along with headIndex, etc.
  // goes TRUE to indicate that some form of currency is detected in
  // scanned image.
  boolean currency_detected;
#endif

} DMBIMAGE, *pDMBIMAGE;


typedef struct DMBFILE_HEADER_ {
  char magic[4];                //Should contain the ASCII O A d i.
  UINT32 version;               //dmbimage version number, we'll start with 1.
  UINT32 fh_size;               //size of the file header (this struct).
  UINT32 dmbimage_size;         //size of the dmbimage struct.
} DMBFILE_HEADER;

# endif /* if SDK_VERSION >= 5 */

/******************************************************************************
*  4. ALLOCS
******************************************************************************/
/******************************************************************************
*  5. FUNCTIONS
******************************************************************************/

/***************************************************************************//**
*  DMBIMAGE_Free
*  Frees entire DMBIMAGE.  Freeing must be first enabled by the consumer
*  currentHeadDMBIndex != MEM_NULL.  This function will clear the
*  consumptionOngoing flag and headDMBIndex upon completion.
*
*  @param dmbP - Pointer to DMBIMAGE
******************************************************************************/
void DMBIMAGE_Free(volatile pDMBIMAGE dmbP);

/***************************************************************************//**
*  DMBIMAGE_GetBitsPerPixel
*  Gets the number of bits per pixel according to bitdepth
*
*  @param dmbP - bitdepth
*  @return Returns the number of bits
******************************************************************************/
UINT8 DMBIMAGE_GetBitsPerPixel(DMBIMAGE_BITDEPTH bitdepth);

/***************************************************************************//**
*  Translate bits-per-pixel to the correct enumeration.
*
*  @param bitDepth - bit depth in bits per pixel.
*  @return Returns the correct enumeration.
******************************************************************************/
DMBIMAGE_BITDEPTH DMBIMAGE_TranslateBitsPerPixel(UINT8 bitdepth);

/**************************************************************************//**
*  DMBIMAGE_QueryMaxDMBsStatus
*  Check to see if the count of allocated DMBs exceed the maxDMBs defined.
*
*  @param dmbP - Pointer to DMBIMAGE
*
*  @return Returns TRUE if the count of allocated DMBs does not exceed
*          the maxDMBs set and the count of parent allocated DMBs also, if exist,
*          does not exceed parent maxDMBs, FALSE otherwise.
******************************************************************************/
boolean DMBIMAGE_QueryMaxDMBsStatus(volatile DMBIMAGE *dmbP);

/**************************************************************************//**
*  DMBIMAGE_Init
*  Initializes the DMBIMAGE per the definition of a DMBIMAGE found above.
*
*  @param dmbP - Pointer to DMBIMAGE
******************************************************************************/

void DMBIMAGE_Init(volatile DMBIMAGE *dmbP);

/**************************************************************************//**
*  DMBIMAGE_IncAllocDMBs
*  Increment allocDMBs and parent allocDMBs if exists.
*
*  @param dmbP - Pointer to DMBIMAGE
******************************************************************************/
void DMBIMAGE_IncAllocDMBs(volatile DMBIMAGE *dmbP);

/**************************************************************************//**
*  DMBIMAGE_IncFreeDMBs
*  Increment freeDMBs and parent freeDMBs if exists.
*
**  @param dmbP - Pointer to DMBIMAGE
******************************************************************************/
void DMBIMAGE_IncFreeDMBs(volatile DMBIMAGE *dmbP);

/**************************************************************************//**
*  DMBIMAGE_ImageFullLoaded
*  @param dmbP - Pointer to DMBIMAGE
*
*  @return Returns TRUE if then DMB image has completed being loaded in memory,
*                  FALSE otherwise.
******************************************************************************/
boolean DMBIMAGE_ImageFullLoaded(pDMBIMAGE dmbP);

/**************************************************************************//**
*  DMBIMAGE_ImageReady
*  @param dmbP - Pointer to DMBIMAGE
*
*  @return Returns TRUE if the DMB image has being created/loaded or completed
*                       being created in memory, FALSE otherwise.
******************************************************************************/
boolean DMBIMAGE_ImageReady(pDMBIMAGE dmbP);

/**************************************************************************//**
*  This routine determines whether a DMBIMAGE is available and valid.
*
*  @param dmbImageP - Pointer to DMBIMAGE
*  @param needValidHeadIndex - TRUE if head DMB Index is required.
*  @param waitDMBImage - TRUE will wait for image to be created, FALSE
*  allows for usage while creation.
*
*  @return Returns TRUE there is a DMB available to for use, FALSE otherwise.
******************************************************************************/
boolean DMBIMAGE_HaveImages(pDMBIMAGE dmbImageP, boolean needValidHeadIndex, boolean waitDMBImage);

/**************************************************************************//**
*  For debug use to print out the DMBIMAGE structure.
*
*  @param dmbP - Pointer to DMBIMAGE
******************************************************************************/
void DMBIMAGE_Display(volatile DMBIMAGE *dmbP);

/**************************************************************************//**
*  This routine initializes a DMBIMAGE of for DMBIMAGE_FORMAT_EXTENT. Only
*  the height is unknown for this DMBIMAGE type. This routine will use
*  DMBIMAGE_Init() to first intialize all DMBIMAGE fields before setting
*  the extent-specific details.
*
*  @param pDMB - Pointer to DMBIMAGE
******************************************************************************/
void DMBIMAGE_InitExtent(volatile DMBIMAGE *pDMB);

/**************************************************************************//**
*  This routine calculates the stride of an image given it's width and
*  bit-depth.
*
*  @param width - Width of DMBIMAGE. See the width definition for more
*  details.
*  @param bitDepth - Bit-depth of the DMBIMAGE. See the bit-depth definition
*  for more details.
*
*  @return Returns stride of the DMBIMAGE.
******************************************************************************/
UINT32 DMBIMAGE_GetStride(UINT32 width, DMBIMAGE_BITDEPTH bitDepth);
#endif  /* _dmbimage_h_ */
